Tangible Software Solutions
C++ to Java Converter Help
Contents
- Folder Conversion
- File & Snippet Conversion
- Command Line Conversion
- Code Formatting Options
- Header File Options
- System Headers
- Library Free Function Replacements
- Conversion Message Options
- Custom String Replacements
- Type & Member Replacements
- Diagnostic Options
- File Encoding Options
- Additions & Omissions
- Package & File Options
- Naming Conventions
- Miscellaneous Options
- Copy Constructors and Copy Assignment
Folder Conversion
The Folder Converter tab allows you to convert all C++ code
within a folder. Once the files are converted, you can then view C++ to Java Converter
comments, compare converted code files to original code files, and view the converted
code folder.
The Conversion History listview displays previously converted sources and allows you to
view remaining C++ to Java Converter comments and view the converted code folder.
File & Snippet Conversion
The File & Snippet Converter tab allows you to convert
C++ code snippets or files. From the left side textbox, you can type
or paste code snippets, insert files, or view C++ to Java Converter sample snippets.
Once a file or snippet is converted, you can select and copy the results, save the
results to a file, or search the results.
Command Line Conversion
C++ to Java Converter can be launched from the command line with
two or three parameters. If you specify folders, the first parameter is the folder containing
the source files that you wish to convert, and the second parameter is the folder that
the converted Java files will be written to. If you specify files, the first parameter
is the source code file that you wish to convert, and the second parameter is the name
of the converted Java file. If a third parameter is supplied, then it is interpreted as
the location of a conversion options file to import before the conversion starts. A conversion options file
has the extension '.opt' and is produced by exporting existing options to an xml file from the converter.
e.g. (folder conversion),
"C++ to Java Converter" "C:\C++ Source Files" "C:\Java Converted Files"
e.g. (file conversion),
"C++ to Java Converter" "C:\C++ Source Files\testfile.cpp" "C:\Java Converted Files\testfile.java"
e.g. (folder conversion with a conversion options file specified),
"C++ to Java Converter" "C:\C++ Source Files" "C:\Java Converted Files" "C:\Options\C++ to Java Converter.opt"
Once the command line conversion is complete, C++ to Java Converter will shut down.
Note that C++ to Java Converter must be in double quotes since the executable name contains spaces.
- Braces: You can choose whether to place opening
braces on the next line after the construct header (default) or at the end of the same line.
You can choose whether to have braces vertically aligned with the construct (default) or
indented. Loops and if or else blocks with a single statement are converted by default
with enclosing braces. If you prefer to exclude braces for these cases then check
the preference to remove braces for single statement loops and if/else blocks.
- Indentation: You can choose whether the converted code uses
tabs or spaces for the leading white space. If you choose tabs for leading white space, then
leading spaces in the original code of the length that you specify are replaced by tabs. If you
choose spaces for leading white space, then tabs in the original code are replaced by spaces
of the length that you specify.
- Spacing: You can choose the degree to which
C++ to Java Converter inserts spaces in the converted code. By default, binary operators
are padded with spaces and control structures have a space inserted after the keyword,
but you can switch off this behavior or insert spaces in other situations.
- Line Endings: By default, the converter separates lines
of code in the output by the Windows line ending \r\n. If you want the non-Windows line
ending \n, then you can choose this option.
- Control Statements: If you
select this option, the converter will break apart control structure statements
(if and while statements) by the main conditions. See the output in the
textbox to see the effect of this option.
- Method Declarations: If you select this
option, the converter will break apart method declarations by the method parameters. See the
output in the textbox to see the effect of this option.
- Method Calls: If you select this
option, the converter will break apart method calls by the method call arguments. See the
output in the textbox to see the effect of this option.
- String Literal Concatenation: If you select this
option, the converter will break apart multiple string literal concatenations to separate
lines. See the output in the textbox to see the effect of this option.
- Missing header files: By default, C++ to Java Converter
will prompt for the location of header files referenced in #include statements.
If you would prefer to have the converter ignore references to header files not found
in the current source code folder or in the 'Additional C++ include folders', you can
check the 'Omit from conversion' option.
- Embedding of header files: By default,
C++ to Java Converter will embed header file code for header files with the
same name as the .c or .cpp file being converted. You can choose to embed
all non-system header files if you prefer or just all non-system header files
specified with quotes. Regardless of which option you select, all non-system
header files are parsed for #define macros and typedef's so that the
appropriate replacements can be made. Also, for code pasted into the
C++ code pane, all non-system header files are embedded.
- Additional C++ #include folders: C++ to Java Converter
will begin searching for #include files in the last selected source code folder,
but you can also specify additional include base paths to search.
- Default system headers: These are system headers
recognized by the converter. System headers are never included in the conversion output.
You can unselect them so that they are not treated as system headers (useful if you have
created header files with the same name and don't want them ignored by the converter).
An asterisk at the end indicates all file names starting with these characters.
- Additional system headers: You can add headers so that
they are also recognized by the converter as system headers and never included in the
conversion output. An asterisk at the end indicates all file names starting with these characters.
Library Free Function Replacements
C++ to Java Converter is primarily a syntax converter, ignoring
most calls to C/C++ library 'free' functions (library functions which don't belong to a class or struct).
However, you can specify your own custom replacements for these free function calls.
These replacements will occur at the end of the conversion process. You specify the new
method name, the expected number of arguments, and whether to transform the function call
to an instance method call (using one of the arguments as the instance variable), or a
static method call (where you specify a class name in addition to the new method name).
Conversion Message Options
On this options dialog, you can customize the comment prefixes
that the converter uses for messages and also toggle the messages that C++ to Java Converter
displays on or off.
You can easily set all or none to display via the 'Select All' and 'Select None' buttons.
Custom String Replacements
C++ to Java Converter allows you to specify your own custom
replacements in the converted Java code. This can be useful for cases where you wish to specify
a replacement for a C++ library data type that isn't handle by C++ to Java Converter.
For each replacement string you can specify the regex option, when to perform the replacement
(pre or post conversion), whether or not to match case, whether to match whole words only,
and whether comments or string literals should be modified. The whole words and string literals
options do not apply if the regex option is selected.
To span mulitple lines, either paste directly into the 'Find' and 'Replacement'
textboxes, or use the escaped characters: \r\n\t.
The "Active" checkbox can be unchecked if you wish to temporarily bypass the replacement.
Replacements are made in the order that they appear on the options dialog. For example,
the second replacement is made to each line of code after the first replacement has already
been made. To change the order of replacements, use the 'Up' and 'Down' buttons.
For an example of the regex option, you could do a custom replacement of "Foo(x)" with "Bar(x)",
where "x" is any argument, by specifying the "Find" field as "Foo(([\sa-zA-Z_$]*))" and the
"Replace" field as "Bar$1". Note that there are differences in various regex engines - the
regex engine used by the converter is .NET System.Text.RegularExpressions.Regex.
Type & Member Replacements
C++ to Java Converter allows you to specify your own custom type and
member replacements in the converted code. This can be useful for cases where you wish to
specify replacements for C++ library member calls of a specific type that are not handled
by C++ to Java Converter.
For each external type, you can specify an optional type replacement and multiple member
replacements. For types, you can specify template/generic types, which may include '?' as
a wildcard type. A wildcard in the replacement type must have a matching wildcard in the
same position in the original type.
e.g., the following will replace all references to type 'Foo' having one 'int' type parameter
with 'Bar', having no type parameters:
original type: Foo<int>
replacement type: Bar
e.g., the following will replace all references to type 'Foo' having one type parameter of any
type with 'Bar', having the same type parameter:
original type: Foo<?>
replacement type: Bar<?>
For each member replacement, you specify the original member name, whether the member is static
or not, and whether the member is a method or a field. You also specify the number of arguments
you expect. To replace C++ operator invocations, specify the original method as an instance
method and use "operator+", "operator-", etc. for the original method name.
For the replacement member, you specify whether the replacement is static or not, and whether
the replacement is a method or a field. You also specify the new list of arguments and can
add literal arguments. For replacement of static methods with instance members, you also
specify the argument position which corresponds to the object instance for the new instance
member. For replacement of instance members with static members, you specify the new class
name used to call the static member (for static methods, you also specify the position in
the argument list to insert the previous instance qualifier, using the string "instance"
(quotes not included) at the appropriate position in the "new argument list" field).
For example, if you want to replace all instance calls to the 'Foo' type method 'Bar'
where you want the instance qualifier to be the new first argument, you would specify
"instance, a1" (quotes not included) for the "new argument list" field, assuming that there
was one argument in the original method calls.
Diagnostic Options
These options are intended to provide information to
Tangible Software Solutions if a conversion is taking longer than expected.
'Record processing by file' instructs the converter to make a record of the files
processed and the time taken for each process. 'Record the last 100 lines of code
parsed before cancelling conversion' instructs the converter to make a record of the
most recent lines parsed before you cancelled the conversion.
File Encoding Options
The converter detects input file encoding from the byte order
mark (BOM), but if the BOM is missing the converter assumes by default that the file encoding
is UTF-8. You can use this option to specify a different default encoding to use in the absence
of a BOM. Output is written in the same encoding as the encoding detected for the original file,
or your default encoding option if the original coding was not detected via the BOM.
For UTF-8, you can choose whether or not to include the BOM for the output - this is normally
used in Windows environments.
Additions & Omissions
- Add to the top of all converted files: If you add text
for this option, that text will be added to the top of every converted file. This option
does not apply to code snippet conversions.
- Omit code regions for these preprocessor tokens: C++ to Java
Converter will remove regions of code from the conversion output which are in preprocessor
blocks positively conditional on any of these tokens (e.g., #ifdef OMIT or #if defined(OMIT)).
- Copy code unconverted for these preprocessor tokens: C++ to
Java Converter will leave regions of code unconverted which are in preprocessor blocks positively
conditional on any of these tokens (e.g., #ifdef COPY or #if defined(COPY)). Any #elif or
#else blocks following the #ifdef section are removed from the conversion output.
Package & File Options
- Package name if namespace is absent: If types in the
original code are not within a namespace, then the converter will use the package name
that you specify here.
- Place types in separate files named after the type: Standard
Java practice is to dedicate a file to a single type (class, interface, or enum).
C++ to Java Converter does this by default, but you can also choose to keep the converted
code in a file structure corresponding to the original file structure.
- Base output folder structure on package structure:
Standard Java practice is to have the source code folder structure mimic the package structure.
C++ to Java Converter does this by default, but you can also choose to keep the converted code
in a folder structure corresponding to the original folder structure.
- Convert to lowercase package names:
Standard Java practice is to use lowercase package names. C++ to Java Converter does this
by default, but you can also choose to leave the original namespace names unchanged.
- Show the original file name for types and method definitions:
When this option is selected, the converter will display a comment with the original file name
for all converted types and method definitions. This is useful for sorting out where the
original types and method definitions came from since the converted file names will be based on
the contained class name according to standard Java practice.
Naming Conventions
By default, the converter does not change naming conventions,
but you can select these options to cause the converter to modify names to conform
to these common Java conventions.
Miscellaneous Options
- Renaming tag for code element conflicts: C++ to Java Converter must occasionally
rename class fields to avoid conflicts since C++ allows fields and inner types with identical
names, but Java does not. You can choose your own renaming tag and whether to place it at
the beginning or end of the original name when this is necessary.
- Renaming tag for Java keyword conflicts: C++ to Java Converter must occasionally
rename identifiers that are keywords in Java. You can choose your own renaming tag and
whether to place it at the beginning or end of the original name when this is necessary.
- Conversion of unsigned integer types:
By default, C++ to Java Converter only provides a warning for unsigned integer types (which
are not available in Java). You can instead choose one of the other two options:
1. use bitmasks to reproduce the unsigned integer behavior or 2. promote to the next
larger integer type. These last two options do not apply to 'unsigned long long'.
- Conversion of std::optional: By default,
C++ to Java Converter converts std::optional to java.util.Optional,
except where the generic type argument is a primitive type - in these cases
the Java wrapper types (e.g., Integer) are used. But you can choose not to use
java.util.Optional or not to use the Java wrapper types for the primitive type argument case.
- Copy non-code files in folder conversions: By default,
the converter does not copy non-code files in folder conversions. If you select this
option, all non-code files are copied to the target folder.
- Expand #define function macros inline: Function-style macros
are expanded inline by default, but you can choose to bypass this behavior. You would
normally bypass this behavior if you plan to rewrite the macros as Java methods.
- Include commented original #define macros in output:
By default the converter leaves the commented original #define macros in the output,
unless you turn off this option.
- Detect copy assignment or construction: By default,
C++ to Java Converter attempts detection of copy assignment and construction.
Turn this option off if you would prefer not to have the converter do this.
- Assign array defaults: By default,
C++ to Java Converter creates a helper class that is referenced for assigning array
defaults to reproduce the same behavior as the original C++ code. Turn this option
off if you would prefer not to have the converter do this.
- Always convert TRUE/FALSE macros to true/false literals:
By default, C++ to Java Converter converts the TRUE/FALSE macros to the true/false
boolean literals. If you always want TRUE/FALSE to convert to their actual C values
1 and 0, then check this option.
- Convert BOOL typedef to boolean: By default,
C++ to Java Converter converts the BOOL typedef to boolean, but you can choose
to convert this typedef to int, which is the original C typedef.
- Convert char, wchar_t, & char16_t pointers to strings: By default,
the converter converts character pointers to strings. We don't convert char32_t since there is
no equivalent in Java to 32-bit characters.
- Convert char, wchar_t, & char16_t arrays to strings: By default,
the converter converts character arrays to strings. We don't convert char32_t since there is
no equivalent in Java to 32-bit characters.
- Convert inferred typing to Java 10 inferred typing: Java 10
allows inferred typing for local variables via the 'var' keyword. Check this option if you
want the converter to convert C++ 'auto' to Java 'var'.
- Use generic type inference (diamond syntax): Select
this option to convert C++ template variable initializations to the streamlined 'diamond
syntax' available since Java 7 (e.g., Foo<Integer> instance = new Foo<>();.
- Assume 'using namespace std' for snippet conversions:
By default, the converter assumes that the original C++ code has a 'using namespace std'
statement for code snippet conversions, unless you uncheck this option.
- Generate method overloads for optional parameters:
By default, C++ to Java Converter generates method overloads for methods with optional
parameters. If you turn off this option, then no method overloads will be generated and
any missing optional arguments will be added to the method calls.
- Convert raw string literals to Java 15 text blocks: Java 15
text blocks are used for conversion of C++ raw string literals if you select this option.
- C/C++ file extensions: If you have C/C++ file extensions
other than the default extensions, then add them here.
Copy Constructors and Copy Assignment
In C++, object variable assignment without using pointers
does not perform reference assignment as in Java. Instead these assignments perform
a bitwise copy by default or performs the action specified in a copy constructor or
assignment operator overload specified in the C++ source code. When C++ to Java Converter
determines that an assignment is likely a copy assignment or a call to a copy constructor,
it converts them to the Java equivalent and adds a warning to the converted code.
e.g., the following C++ code:
Foo g;
Foo f = g; //uses the copy constructor of type 'Foo'
f = g; //uses the assignment operator overload of type 'Foo'
converts to the Java equivalent:
Foo g = new Foo();
Foo f = new Foo(g);
f.copyFrom(g);
The original copy constructor is converted directly to a Java constructor, and the original
assignment operator overload is converted to a 'copyFrom' method (since overloading the
assignment operator is not possible in Java). C++ compilers automatically generate both
the copy constructor and the assignment operator overload if one isn't specified in the
C++ source code, but C++ to Java Converter will only convert existing copy constructors
and assignment operator overloads and will not create default methods. You may need to
code the copy constructor and/or the 'copyFrom' method if the original C++ source code
relied on the default methods created by the C++ compiler.
Copyright © Tangible Software Solutions, Inc.